/*
 * NOTE: This copyright does *not* cover user programs that use HQ
 * program services by normal system calls through the application
 * program interfaces provided as part of the Hyperic Plug-in Development
 * Kit or the Hyperic Client Development Kit - this is merely considered
 * normal use of the program, and does *not* fall under the heading of
 * "derived work".
 *
 * Copyright (C) [2004, 2005, 2006], Hyperic, Inc.
 * This file is part of HQ.
 *
 * HQ is free software; you can redistribute it and/or modify
 * it under the terms version 2 of the GNU General Public License as
 * published by the Free Software Foundation. This program is distributed
 * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
 * even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 * PARTICULAR PURPOSE. See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
 * USA.
 */

package features;

import java.util.List;
import java.util.Map;

import org.snmp4j.CommandResponder;
import org.snmp4j.PDU;
import org.snmp4j.event.ResponseEvent;
import org.snmp4j.event.ResponseListener;

import alarm.Alarm;

/**
 * Generic interface for any version of the SNMP protocol.
 * Use the SNMPClient.getSession to get an instance
 * of a class that implements this interface.
 */
public interface SNMPSession {

    /**
     * Retrieve a single data variable from an SNMP agent.
     *
     * @param mibName The name of the variable to retrieve.
     *
     * @return a SNMPValue object representing the value of the
     * variable.
     *
     * @exception SNMPException if an error occurs communicating
     * with the SNMP agent.
     */
    public SNMPValue getSingleValue(String mibName)
        throws SNMPException;

    /**
     * Retrieve the value that is equal to or logically next after
     * the specified name.
     *
     * @param mibName The name of the MIB variable to start looking.
     *
     * @return An SNMPValue object representing the value of the
     * specified MIB name, or if not found, the next logical MIB
     * name.
     *
     * @exception SNMPException if an error occurs communicating
     * with the SNMP agent.
     */
    public SNMPValue getNextValue(String mibName)
        throws SNMPException;

    /**
     * Retrieves all values from a column of an SNMP table.
     *
     * @param mibName The name of the column of the SNMP table.
     *
     * @return a List of SNMPValue objects representing the values
     * found in the column.
     *
     * @exception SNMPException if an error occurs communicating
     * with the SNMP agent.
     */
    public List<SNMPValue> getColumn(String mibName)
        throws SNMPException;

    public Map<String, SNMPValue> getTable(String mibName, int index)
        throws SNMPException;

	/**
	 * The GETBULK operation is normally used for retrieving large amount of
	 * data, particularly from large tables. A GETBULK request is made by giving
	 * an OID list along with a Max-Repetitions value and a Nonrepeaters value.
	 * 
	 * <br><br>
	 * 
	 * The GETBULK operation performs a continuous GETNEXT operation based on
	 * the Max-Repetitions value. The Nonrepeaters value determines the number
	 * of variables in the variable list for which a simple GETNEXT operation
	 * has to be done. For the remaining variables, the continuous GETNEXT
	 * operation is done based on the Max-Repetitions value.
	 * 
	 *  <br><br>
	 * 
	 * In other words, the SNMP GETBULK operation does a simple GETNEXT
	 * operation for the first N variable bindings in the request and does M
	 * GETNEXT operation (continuous) for each of the remaining R variable
	 * bindings in the request list where
	 * 
	 *  <br><br>
	 * 
	 * <b>N</b> is the minimum of:
	 * <dd>-the value of the Non-Repeaters field in the request<br>
	 * <dd>-the number of variable bindings in the request<br><br>
	 * <b>M</b> is the Max-Repetitions field of the request<br><br>
	 * 
	 * <b>R</b> is the maximum of the number of: 
	 * <dd>-variable bindings in the request</b>
	 * <dd>-zero <br><br>
	 * 
	 * Thus the total number of varbinds in the response message is (N + M x R).
	 */
	
	/**
	 * @param mibName
	 * @return
	 * @throws SNMPException
	 */
    public List<SNMPValue> getBulk(String mibName)
        throws SNMPException;
    
    public CommandResponder registerAlarm(Alarm alarm) throws SNMPException;
    
    public CommandResponder registerAlarm(Alarm alarm, CommandResponder commandResponder) throws SNMPException;

	public void init(String ip, String defaultPortString, String defaultCommunity) throws SNMPException;
	
	public ResponseEvent set(PDU pdu);
}
